home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 49 / Amiga Format CD49 (2000-01-17)(Future Publishing)(GB)(Track 1 of 3)[!][issue 2000-02].iso / -serious- / workbench / visualprefs / docsenglish / vp-developer.doc < prev    next >
Text File  |  1999-11-29  |  6KB  |  140 lines
  1.  
  2.                                Introducing
  3.  
  4.                     THE VISUALPREFS DEVELOPER INTERFACE
  5.  
  6.                             A work in progress
  7.  
  8.  
  9. If you're a developer, you can take advantage of some features of VisualPrefs.
  10.  
  11. Although there's not a full developer API for VisualPrefs yet, it's already
  12. possible to use the BOOPSI classes that VisualPrefs adds to the system.
  13.  
  14. The purpose of these classes is to give programmers an easy way to get the
  15. "VisualPrefs look", without having to wait for me to implement a patch for
  16. their applications in VisualPrefs. ;-)
  17.  
  18. Currently there's just one class:
  19.  
  20. "tbiclass" - the titlebar image class
  21.  
  22. This class provides the most commonly used images for gadgets added by
  23. applications to the titlebar of their windows. Examples of this are the
  24. ubiquitous "iconify" gadget or DirOpus 5's "padlock" gadget.
  25.  
  26. All programs using this class will automatically get the same look for their
  27. titlebar images if VisualPrefs is running. This is probably better than
  28. having myriads of different versions of the same image...
  29.  
  30. You can use "tbiclass" just like "sysiclass"; they're both sub-classes of
  31. "imageclass". A "tbiclass" image can be created by calling NewObject() with
  32. the following tags:
  33.  
  34. SYSIA_DrawInfo - This is absolutely mandatory. You MUST pass a DrawInfo
  35.                  pointer to "tbiclass" or NewObject() will fail.
  36.  
  37. SYSIA_Which - To specify which image you want; currently there are six image
  38.               types:
  39.  
  40.               POPUPIMAGE    - A MUI "pop-up" titlebar gadget image
  41.               MUIIMAGE      - A MUI "settings" titlebar gadget image
  42.               SNAPSHOTIMAGE - A MUI "snapshot" titlebar gadget image
  43.               ICONIFYIMAGE  - An "iconify" titlebar gadget image
  44.               PADLOCKIMAGE  - A DirOpus "padlock" titlebar gadget image
  45.               TBFRAMEIMAGE  - A general-purpose empty titlebar gadget image
  46.  
  47. IA_Width, IA_Height - These are only recognized by the TBFRAMEIMAGE type;
  48.                       the other image types ignore them and always have
  49.                       the same size of the depth gadget image.
  50.  
  51. SYSIA_ReferenceFont - This is only recognized by the TBFRAMEIMAGE type;
  52.                       the other image types ignore it and always have
  53.                       the same height of the depth gadget image.
  54.  
  55. You can also use this tag with GetAttr():
  56.  
  57. TBIA_ContentsBox - To ask the image about the position and size of its
  58.                    actual "contents box" relative to the image itself.
  59.                    Said box is the part where, if you need to, you can
  60.                    add any further custom imagery. This probably only
  61.                    makes sense with TBFRAMEIMAGE images. To position
  62.                    correctly the box, you should add its Left and Top
  63.                    offsets to those of the image. Note that, even within
  64.                    the returned dimensions, you should always leave a
  65.                    small space (like two pixels) around your imagery,
  66.                    to achieve better-looking results. This is a read-only
  67.                    attribute; the value you pass to this tag must be a
  68.                    pointer to an IBox structure. Do NOT pass a longword
  69.                    pointer! (Available since VisualPrefs 41.35)
  70.  
  71. Of course, if NewObject() fails, you should provide a built-in fallback image
  72. for your titlebar gadget. However, I have released a disk-based freeware
  73. "tbiclass" image class (dev/gui/titlebar_ic.lha) which you can include in the
  74. distribution of your applications. This class will provide the needed images
  75. and will be automatically replaced by the VisualPrefs one if it is present.
  76. Therefore, you can keep your built-in images very simple, or not having
  77. them at all ;-)
  78.  
  79. It's important to note that all "tbiclass" image instances will have an
  80. Image->LeftEdge value of -1. This shouldn't be modified, and you should
  81. place your titlebar gadgets accordingly. The reason for this apparently
  82. strange behavior is that Intuition titlebar gadget images, too, work this
  83. way, and we should try to stay as compatible with Intuition as possible.
  84.  
  85. Also, make sure you adjust your gadget's size if necessary, to adapt it
  86. to the returned image's size.
  87.  
  88. An example of all this could be:
  89.  
  90.    ...
  91.  
  92.    /* Create the image */
  93.  
  94.    if (!(iconifyimage = NewObject(NULL,"tbiclass",SYSIA_Which,ICONIFYIMAGE,
  95.                                                   SYSIA_DrawInfo,dri,
  96.                                                   TAG_END)))
  97.    {
  98.       iconifyimage = builtin_iconifyimage;
  99.    }
  100.  
  101.    /* Use the image */
  102.  
  103.    gad->GadgetRender = iconifyimage;
  104.    ...
  105.  
  106.    /* Free the image */
  107.  
  108.    if (iconifyimage != builtin_iconifyimage) DisposeObject(iconifyimage);
  109.  
  110.    ...
  111.  
  112. That's all. The real include file for "tbiclass" is in the Aminet stand-alone
  113. release, anyway all you need in order to use "tbiclass" in your applications
  114. is to paste the following few lines at the beginning of your source code. :-]
  115.  
  116. ------- cut here -------8<------- cut here -------8<------- cut here -------
  117.  
  118. #define POPUPIMAGE    (101)
  119. #define MUIIMAGE      (102)
  120. #define SNAPSHOTIMAGE (103)
  121. #define ICONIFYIMAGE  (104)
  122. #define PADLOCKIMAGE  (105)
  123. #define TBFRAMEIMAGE  (106)
  124.  
  125. #define TBIA_Dummy       (TAG_USER + 0x0B0000)
  126. #define TBIA_ContentsBox (TBIA_Dummy + 0x0001)
  127.  
  128. ------- cut here -------8<------- cut here -------8<------- cut here -------
  129.  
  130. There's already an application using "tbiclass", ViNCEd by Thomas Richter.
  131.  
  132. I hope you will also support "tbiclass" and contribute this way to finally
  133. give a consistent appearance to all titlebar gadgets used in applications!
  134.  
  135. Thank you,
  136.                                       Massimo Tantignone (tanti@intercom.it)
  137.  
  138.  
  139.  
  140.